////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package org.teotigraphix.swizplugin.registry
{

/**
 * The <strong>IExtensionPoint</strong> interface is a lightweight extension
 * point descriptor for <code>IExtensionRegistry</code> extension points.
 * 
 * <p>The <strong>IExtensionPoint</strong> represents an item that has been
 * added to the <code>IExtensionRegistry</code> through 
 * <code>IExtensionRegistry#addExtensionPoint()</code> method.</p>
 * 
 * <p>This interface will be used in application specific code, the 
 * <code>IPluginExtensionPoint</code> interface is mainly used at start-up
 * for declarative MXML implementations of extension points found in 
 * <code>IPlugin</code> MXML declarations.</p>
 * 
 * <p>Once an <code>IPluginExtensionPoint</code> is parsed by the extension
 * registry, it becomes an <code>IExtensionPoint</code> parented by the
 * <code>IExtensionRegistry</code>.</p>
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 * 
 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#addExtensionPoint()
 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#getExtensionDescriptorsFor()
 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#getExtensionFor()
 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#getExtensionPoint()
 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#getExtensionPoints()
 */
public interface IExtensionPoint
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------
	
	//----------------------------------
	//  contributor
	//----------------------------------
	
	/**
	 * Returns the <code>IBundle</code>'s <code>IContributor</code> instance.
	 */
	function get contributor():IContributor;
	
	//----------------------------------
	//  simpleID
	//----------------------------------
	
	/**
	 * Returns the String identifier after the namespace identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace</code>,
	 * this property returns <strong>trace</strong>.</p>
	 */
	function get simpleID():String;
	
	//----------------------------------
	//  namespaceID
	//----------------------------------
	
	/**
	 * Returns the string before the simple identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace</code>,
	 * this property returns <strong>com.acme</strong>.</p>
	 */
	function get namespaceID():String;
	
	//----------------------------------
	//  uniqueID
	//----------------------------------
	
	/**
	 * Returns the whole string extension point identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace</code>,
	 * this property returns <strong>com.acme.trace</strong>.</p>
	 */
	function get uniqueID():String;
	
	//----------------------------------
	//  internalID
	//----------------------------------
	
	/**
	 * The internal registry id.
	 */
	function get internalID():int;
	
	//----------------------------------
	//  label
	//----------------------------------
	
	/**
	 * Returns the label of the extension, <code>name</code> in mxml.
	 */
	function get label():String;
	
	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------
	
	/**
	 * Returns all <code>IExtensionDescriptor</code>s found in the registry
	 * for this extension point.
	 * 
	 * <p>Note: this method will return all first level descriptors of 
	 * extensions parented by this extension point.</p>
	 * 
	 * @return An Array of <code>IExtensionDescriptor</code> or an empty Array,
	 * never <code>null</code>.
	 */
	function getExtensionDescriptors():Array;
	
	/**
	 * Returns all <code>IExtension</code>s found in the registry parented by this 
	 * extension point.
	 * 
	 * @return An Array of <code>IExtension</code> or an empty Array,
	 * never <code>null</code>.
	 */
	function getExtensions():Array; 
	
	/**
	 * Return an <code>IExtension</code> parented by this extension point.
	 * 
	 * <p>Note: not all extensions will have a unique identifier, it is not required
	 * since a lot of work is taken care of by child descriptors with unique 
	 * identifiers.</p>
	 * 
	 * @param extensionID The unique identifier of the extension.
	 * @return An <code>IExtension</code> or <code>null</code> if not found.
	 */
	function getExtension(extensionID:String):IExtension;
}
}